docs: audit and fix documentation architecture#1049
docs: audit and fix documentation architecture#10491PoPTRoN wants to merge 1 commit intokubestellar:mainfrom
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
kubestellar-prow
bot
added
the
dco-signoff: no
✅ Deploy Preview for kubestellar-docs ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Welcome to KubeStellar! 🚀 Thank you for submitting this Pull Request. Before your PR can be merged, please ensure: ✅ DCO Sign-off - All commits must be signed off with ✅ PR Title - Must start with an emoji: ✨ (feature), 🐛 (bug fix), 📖 (docs), 🌱 (infra/tests), Getting Started with KubeStellar: Contributor Resources:
🌟 Help KubeStellar Grow - We Need Adopters! Our roadmap is driven entirely by adopter feedback. Whether you're using KubeStellar yourself or know someone who could benefit from multi-cluster Kubernetes: 📋 Take our Multi-Cluster Survey - Share your use cases and help shape our direction! A maintainer will review your PR soon. Feel free to ask questions in the comments or on Slack! |
github-actions
bot
added
documentation
kubestellar-prow
bot
added
needs-ok-to-test
|
Hi @1PoPTRoN. Thanks for your PR. I'm waiting for a kubestellar member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
There was a problem hiding this comment.
Pull request overview
This PR audits and restructures the documentation site to fix build stability issues, clean up navigation/content architecture, and lay groundwork for i18n (notably sidebar title translations) while keeping routes stable.
Changes:
- Added
next-intlsupport in the docs UI (provider setup + sidebar title translation mapping). - Updated docs navigation structure (restoring/adding missing links, removing duplicates) and removed leftover MkDocs artifacts.
- Cleaned up and consolidated docs content (hide internal TODOs, merge/remove redundant console card docs, add a developer guide).
Reviewed changes
Copilot reviewed 16 out of 17 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| src/components/docs/DocsSidebar.tsx | Adds next-intl translations for sidebar titles via a hardcoded title→key mapping. |
| src/app/docs/page-map.ts | Updates static nav structure (adds “Related Projects”, removes duplicate “Quick Start”, formatting tweaks). |
| src/app/docs/layout.tsx | Wraps docs app with NextIntlClientProvider and loads message bundle server-side. |
| next.config.ts | Adds a server-side localStorage mock to avoid build-time failures from client-only dependencies. |
| messages/en.json | Introduces docs.* translation keys used by the sidebar. |
| docs/DEVELOPER_GUIDE.md | Adds contributor guidance for docs architecture, images, and i18n workflow. |
| CONTRIBUTING.md | Updates repository architecture description to reflect locally-managed docs content. |
| docs/content/console/all-cards.md | Expands the “Arcade” list in the unified cards reference. |
| docs/content/console/console-cards.md | Removes redundant console card reference (content consolidation). |
| docs/content/console/cards.md | Removes redundant console card types doc (content consolidation). |
| docs/content/direct/packaging.md | Hides an inline TODO from public rendering using JSX comments. |
| docs/content/direct/example-scenarios.md | Hides an inline TODO from public rendering using JSX comments. |
| docs/content/direct/control.md | Hides an inline TODO from public rendering using JSX comments. |
| docs/content/direct/binding.md | Hides inline TODO notes using JSX comments. |
| docs/content/direct/acquire-hosting-cluster.md | Hides an inline TODO from public rendering using JSX comments. |
| docs/content/.pages | Removes leftover MkDocs navigation artifact file. |
| package-lock.json | Lockfile updates (notably removing some peer: true metadata entries). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // Mapping of hardcoded titles to translation keys | ||
| const titleToKey: Record<string, string> = { | ||
| 'What is KubeStellar?': 'whatIsKubeStellar', | ||
| 'Overview': 'overview', | ||
| 'Architecture': 'architecture', | ||
| 'User Guide': 'userGuide', | ||
| 'Guide Overview': 'guideOverview', | ||
| 'Observability': 'observability', | ||
| 'Getting Started': 'gettingStarted', | ||
| 'Related Projects': 'relatedProjects', | ||
| 'Release Notes': 'releaseNotes', | ||
| 'Roadmap': 'roadmap' | ||
| }; |
There was a problem hiding this comment.
titleToKey is created inside renderMenuItem, so a new object is allocated for every menu item on every render. Move this mapping to module scope (or memoize it) to avoid unnecessary work and keep the translation mapping in one stable place.
| if (displayTitle && titleToKey[displayTitle]) { | ||
| try { | ||
| const translated = t(titleToKey[displayTitle]); | ||
| if (translated) displayTitle = translated; | ||
| // eslint-disable-next-line @typescript-eslint/no-unused-vars | ||
| } catch (e) { | ||
| // Fallback to original | ||
| } |
There was a problem hiding this comment.
The translation fallback uses catch (e) plus an eslint disable for unused vars. Since the error value isn't used, prefer catch { ... } (optional catch binding) to avoid lint suppression, or handle missing keys explicitly (e.g., check existence before calling t).
| // Backward compatibility for dot notation if used in files | ||
| else if (displayTitle && displayTitle.includes('.')) { | ||
| try { | ||
| const translated = t(displayTitle.split('.')[1]); |
There was a problem hiding this comment.
The dot-notation compatibility path uses displayTitle.split('.')[1], which only works for exactly one dot (e.g. docs.overview) and will translate the wrong segment for deeper keys (e.g. a.b.c -> b). If this is intended to support namespaced keys, use the last segment (or remove this branch if not needed).
| const translated = t(displayTitle.split('.')[1]); | |
| const parts = displayTitle.split('.'); | |
| const translated = t(parts[parts.length - 1]); |
| <html lang="en" suppressHydrationWarning> | ||
| <body className={`${inter.variable} ${jetbrainsMono.variable} antialiased`}> | ||
| <ThemeProvider attribute="class" defaultTheme="dark" enableSystem> | ||
| <DocsProvider> | ||
| <div className="flex flex-col min-h-screen"> | ||
| <DocsBanner /> | ||
| <Suspense fallback={<div className="h-16" />}> | ||
| <DocsNavbar /> | ||
| </Suspense> | ||
| <main className="flex-1"> | ||
| {children} | ||
| </main> | ||
| <DocsFooter /> | ||
| </div> | ||
| </DocsProvider> | ||
| </ThemeProvider> | ||
| <NextIntlClientProvider messages={messages} locale="en"> | ||
| <ThemeProvider attribute="class" defaultTheme="dark" enableSystem> |
There was a problem hiding this comment.
NextIntlClientProvider is hard-coded to locale="en" while getMessages() can resolve locale dynamically (e.g., from cookies/headers). This prevents docs UI strings from ever switching languages and can also desync locale vs the loaded message bundle. Prefer using getLocale() (or the locale returned by your request config) for both <html lang> and the provider’s locale prop.
| // Mock localStorage for server-side build to prevent TypeError from client-side dependencies | ||
| if (typeof window === "undefined") { | ||
| (global as any).localStorage = { | ||
| getItem: () => null, | ||
| setItem: () => {}, | ||
| removeItem: () => {}, | ||
| clear: () => {}, | ||
| length: 0, | ||
| key: () => null, | ||
| }; | ||
| } |
There was a problem hiding this comment.
Mocking localStorage by mutating the Node global in next.config.ts applies to all phases (dev server, build, etc.) and can mask real SSR issues or change server-runtime behavior of dependencies that feature-detect localStorage. Consider scoping this to the production build phase (e.g. PHASE_PRODUCTION_BUILD) and/or only defining it when globalThis.localStorage is absent, instead of unconditionally setting it.
| 1. **Add the File**: Create a `.md` or `.mdx` file in `docs/content/` (or a subfolder). | ||
| 2. **Update Navigation**: Add an entry to the `NAV_STRUCTURE` array in [page-map.ts](file:///Users/p0ptr0n/Documents/c0des/LFX/docs/src/app/docs/page-map.ts). |
There was a problem hiding this comment.
These links point to a local file:///Users/... path, which won’t work for other contributors or on GitHub. Use a relative repo link instead (e.g. src/app/docs/page-map.ts) or a standard GitHub URL.
| - **Events** - Event timeline and filtering | ||
| - **Data Compliance** - Data classification and compliance checks | ||
| - **Arcade** - Interactive visualizations | ||
| - **Data Compliance** - Data classification and compliance checks |
There was a problem hiding this comment.
This section now lists Data Compliance twice (duplicate bullet). Remove one of the entries to avoid redundancy in the rendered docs.
| - **Data Compliance** - Data classification and compliance checks |
Signed-off-by: 1PoPTRoN <vrxn.arp1traj@gmail.com>
1PoPTRoN
force-pushed
the
docs-fix-and-audit
branch
from
4880251 to
0509597
Compare
kubestellar-prow
bot
added
dco-signoff: yes
1PoPTRoN
changed the title
|
Hi @kubestellar/maintainers, I have completed the documentation audit and fixed the production build issues. I've signed-off the commit and updated the PR title to follow conventions. |
1 participant
This PR performs a comprehensive audit and cleanup of the documentation site, fixing core build issues and implementing a scalable infrastructure for multi-language support.
🛠 Infrastructure & Build Fixes
localStorage: Resolved a production build failure (TypeError: localStorage.getItem is not a function) by mocking client-side globals in next.config.ts. This ensures CI/CD stability.next-intlsupport intoDocsSidebar.tsx. This allows sidebar titles to be translated while maintaining stable URL routes (mapping hardcoded English titles to translation keys).📚 Content & Architecture
all-cards.md).TODOmarkers using JSX comments{/* TODO: ... */}so the public site looks finished for end-users while preserving developer notes.✅ Verification
npm run build(Exit code 0).💡 Note for Reviewers
I identified several "orphaned" documents (files present in the directory but not linked in the navigation) and integrated them into a new "Related Projects" section to provide a complete view of the KubeStellar ecosystem.